// 《围棋》作者版权所有。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

// 此文件实现调用和选择器表达式的类型检查。

package types2

import (
	"cmd/compile/internal/syntax"
	"strings"
	"unicode"
)

// funcInst type检查函数实例化inst并在x中返回结果。
// 操作数x必须是inst.x的求值值，其类型必须是签名。
func (check *Checker) funcInst(x *operand, inst *syntax.IndexExpr) {
	if !check.allowVersion(check.pkg, 1, 18) {
		check.versionErrorf(inst.Pos(), "go1.18", "function instantiation")
	}

	xlist := unpackExpr(inst.Index)
	targs := check.typeList(xlist)
	if targs == nil {
		x.mode = invalid
		x.expr = inst
		return
	}
	assert(len(targs) == len(xlist))

	// 检查类型参数的数量（got）与类型参数的数量（want）
	sig := x.typ.(*Signature)
	got, want := len(targs), sig.TypeParams().Len()
	if !useConstraintTypeInference && got != want || got > want {
		check.errorf(xlist[got-1], "got %d type arguments but want %d", got, want)
		x.mode = invalid
		x.expr = inst
		return
	}

	if got < want {
		targs = check.infer(inst.Pos(), sig.TypeParams().list(), targs, nil, nil)
		if targs == nil {
			// 已报告错误
			x.mode = invalid
			x.expr = inst
			return
		}
		got = len(targs)
	}
	assert(got == want)

	// 实例化函数签名
	res := check.instantiateSignature(x.Pos(), sig, targs, xlist)
	assert(res.TypeParams().Len() == 0) // 签名不再通用
	check.recordInstance(inst.X, targs, res)
	x.typ = res
	x.mode = value
	x.expr = inst
}

func (check *Checker) instantiateSignature(pos syntax.Pos, typ *Signature, targs []Type, xlist []syntax.Expr) (res *Signature) {
	assert(check != nil)
	assert(len(targs) == typ.TypeParams().Len())

	if check.conf.Trace {
		check.trace(pos, "-- instantiating %s with %s", typ, targs)
		check.indent++
		defer func() {
			check.indent--
			check.trace(pos, "=> %s (under = %s)", res, res.Underlying())
		}()
	}

	inst := check.instance(pos, typ, targs, check.bestContext(nil)).(*Signature)
	assert(len(xlist) <= len(targs))

	// 延迟验证实例化（was问题#50450）
	check.later(func() {
		tparams := typ.TypeParams().list()
		if i, err := check.verify(pos, tparams, targs); err != nil {
			// 报告错误的最佳位置
			pos := pos
			if i < len(xlist) {
				pos = syntax.StartPos(xlist[i])
			}
			check.softErrorf(pos, "%s", err)
		} else {
			check.mono.recordInstance(check.pkg, pos, tparams, targs, xlist)
		}
	})

	return inst
}

func (check *Checker) callExpr(x *operand, call *syntax.CallExpr) exprKind {
	var inst *syntax.IndexExpr // 函数实例化，如果有
	if iexpr, _ := call.Fun.(*syntax.IndexExpr); iexpr != nil {
		if check.indexExpr(x, iexpr) {
			// 将函数实例化延迟到参数检查，
			// 在这里，我们将类型
			// 推理的类型和值参数组合在一起。
			assert(x.mode == value)
			inst = iexpr
		}
		x.expr = iexpr
		check.record(x)
	} else {
		check.exprOrType(x, call.Fun, true)
	}
	// x.typ可能是泛型

	switch x.mode {
	case invalid:
		check.use(call.ArgList...)
		x.expr = call
		return statement

	case typexpr:
		// 转换
		check.nonGeneric(x)
		if x.mode == invalid {
			return conversion
		}
		T := x.typ
		x.mode = invalid
		switch n := len(call.ArgList); n {
		case 0:
			check.errorf(call, "missing argument in conversion to %s", T)
		case 1:
			check.expr(x, call.ArgList[0])
			if x.mode != invalid {
				if t, _ := under(T).(*Interface); t != nil && !isTypeParam(T) {
					if !t.IsMethodSet() {
						check.errorf(call, "cannot use interface %s in conversion (contains specific type constraints or is comparable)", T)
						break
					}
				}
				if call.HasDots {
					check.errorf(call.ArgList[0], "invalid use of ... in type conversion to %s", T)
					break
				}
				check.conversion(x, T)
			}
		default:
			check.use(call.ArgList...)
			check.errorf(call.ArgList[n-1], "too many arguments in conversion to %s", T)
		}
		x.expr = call
		return conversion

	case builtin:
		// 此处无需检查非泛型
		id := x.id
		if !check.builtin(x, call, id) {
			x.mode = invalid
		}
		x.expr = call
		// 非常量结果意味着函数调用
		if x.mode != invalid && x.mode != constant_ {
			check.hasCallOrRecv = true
		}
		return predeclaredFuncs[id].kind
	}

	// 普通函数/方法调用
	// 签名可能是泛型
	cgocall := x.mode == cgofunc

	// 如果所有类型都有相同的签名，则可以“调用”类型参数
	sig, _ := coreType(x.typ).(*Signature)
	if sig == nil {
		check.errorf(x, invalidOp+"cannot call non-function %s", x)
		x.mode = invalid
		x.expr = call
		return statement
	}

	// 计算类型参数，如果有
	var xlist []syntax.Expr
	var targs []Type
	if inst != nil {
		xlist = unpackExpr(inst.Index)
		targs = check.typeList(xlist)
		if targs == nil {
			check.use(call.ArgList...)
			x.mode = invalid
			x.expr = call
			return statement
		}
		assert(len(targs) == len(xlist))

		// 检查类型参数的数量（got）与类型参数的数量（want）
		got, want := len(targs), sig.TypeParams().Len()
		if got > want {
			check.errorf(xlist[want], "got %d type arguments but want %d", got, want)
			check.use(call.ArgList...)
			x.mode = invalid
			x.expr = call
			return statement
		}
	}

	// 计算参数
	args, _ := check.exprList(call.ArgList, false)
	isGeneric := sig.TypeParams().Len() > 0
	sig = check.arguments(call, sig, targs, args, xlist)

	if isGeneric && sig.TypeParams().Len() == 0 {
		// 更新记录的调用类型。有趣的是它的实例化类型
		check.recordTypeAndValue(call.Fun, value, sig, nil)
	}

	// 确定结果
	switch sig.results.Len() {
	case 0:
		x.mode = novalue
	case 1:
		if cgocall {
			x.mode = commaerr
		} else {
			x.mode = value
		}
		x.typ = sig.results.vars[0].typ // 解包元组
	default:
		x.mode = value
		x.typ = sig.results
	}
	x.expr = call
	check.hasCallOrRecv = true

	// 如果类型推断失败，参数化结果必须无效
	// （操作数不能有参数化类型）
	if x.mode == value && sig.TypeParams().Len() > 0 && isParameterized(sig.TypeParams().list(), x.typ) {
		x.mode = invalid
	}

	return statement
}

func (check *Checker) exprList(elist []syntax.Expr, allowCommaOk bool) (xlist []*operand, commaOk bool) {
	switch len(elist) {
	case 0:
		// 无需执行

	case 1:
		// 单个（可能是逗号ok）值，or函数返回多个值
		e := elist[0]
		var x operand
		check.multiExpr(&x, e)
		if t, ok := x.typ.(*Tuple); ok && x.mode != invalid {
			// 多个值
			xlist = make([]*operand, t.Len())
			for i, v := range t.vars {
				xlist[i] = &operand{mode: value, expr: e, typ: v.typ}
			}
			break
		}

		// 恰好一个（可能无效或逗号ok）值
		xlist = []*operand{&x}
		if allowCommaOk && (x.mode == mapindex || x.mode == commaok || x.mode == commaerr) {
			x.mode = value
			xlist = append(xlist, &operand{mode: value, expr: e, typ: Typ[UntypedBool]})
			commaOk = true
		}

	default:
		// 多个（可能无效）值
		xlist = make([]*operand, len(elist))
		for i, e := range elist {
			var x operand
			check.expr(&x, e)
			xlist[i] = &x
		}
	}

	return
}

// xlist是源代码中提供的类型参数表达式列表。
func (check *Checker) arguments(call *syntax.CallExpr, sig *Signature, targs []Type, args []*operand, xlist []syntax.Expr) (rsig *Signature) {
	rsig = sig

	// TODO（gri）尝试消除这个额外的验证循环
	for _, a := range args {
		switch a.mode {
		case typexpr:
			check.errorf(a, "%s used as value", a)
			return
		case invalid:
			return
		}
	}

	// 函数调用参数/参数计数要求
	// 
	// |标准调用|点点点调用| 
	// /---------------------------------------------------------------------------+---------------------------------+
	// 标准函数| nargs==npars |无效|
	// /------------------+-------------+-------------+
	// 变量函数| nargs>=npars-1 | nargs==npars | 
	// /-------------+-------------+-------------+

	nargs := len(args)
	npars := sig.params.Len()
	ddd := call.HasDots

	// 设置参数
	sigParams := sig.params // 为变量函数进行调整（空参数列表可能为零！）
	adjusted := false       // 表示SIGPARMS是否不同于t.params 
	if sig.variadic {
		if ddd {
			// 变量函数（a，b，c…）
			if len(call.ArgList) == 1 && nargs > 1 {
				// f（）。。。如果f（）是多值
				// 则不允许检查。errorf（call.省略号，“不能使用…与%d值%s一起使用”，nargs，call.ArgList[0]）
				check.errorf(call, "cannot use ... with %d-valued %s", nargs, call.ArgList[0])
				return
			}
		} else {
			// 变量函数（a，b，c）
			if nargs >= npars-1 {
				// 为参数创建自定义参数：保留
				// 第一个npars-1参数，并为
				// 每个映射到。。。参数
				vars := make([]*Var, npars-1) // npars>0用于变量函数
				copy(vars, sig.params.vars)
				last := sig.params.vars[npars-1]
				typ := last.typ.(*Slice).elem
				for len(vars) < nargs {
					vars = append(vars, NewParam(last.pos, last.pkg, last.name, typ))
				}
				sigParams = NewTuple(vars...) // 可能为零！
				adjusted = true
				npars = nargs
			} else {
				// nargs<npars-1 
				npars-- // 查看下面的正确错误消息
			}
		}
	} else {
		if ddd {
			// 标准函数（a、b、c…）
			// 检查。errorf（call.省略号，“无法在调用非变量%s时使用…调用”，call.Fun）
			check.errorf(call, "cannot use ... in call to non-variadic %s", call.Fun)
			return
		}
		// 标准函数（a，b，c）
	}

	// 检查参数计数
	if nargs != npars {
		var at poser = call
		qualifier := "not enough"
		if nargs > npars {
			at = args[npars].expr // 首先报告额外参数
			qualifier = "too many"
		} else if nargs > 0 {
			at = args[nargs-1].expr // 最后报告参数
		}
		// 处理由零元组表示的空参数列表
		var params []*Var
		if sig.params != nil {
			params = sig.params.vars
		}
		var err error_
		err.errorf(at, "%s arguments in call to %s", qualifier, call.Fun)
		err.errorf(nopos, "have %s", check.typesSummary(operandTypes(args), false))
		err.errorf(nopos, "want %s", check.typesSummary(varTypes(params), sig.variadic))
		check.report(&err)
		return
	}

	// 推断类型参数和必要时实例化签名
	if sig.TypeParams().Len() > 0 {
		if !check.allowVersion(check.pkg, 1, 18) {
			if iexpr, _ := call.Fun.(*syntax.IndexExpr); iexpr != nil {
				check.versionErrorf(iexpr.Pos(), "go1.18", "function instantiation")
			} else {
				check.versionErrorf(call.Pos(), "go1.18", "implicit function instantiation")
			}
		}
		targs := check.infer(call.Pos(), sig.TypeParams().list(), targs, sigParams, args)
		if targs == nil {
			return // 已报告错误
		}

		// 计算结果签名
		rsig = check.instantiateSignature(call.Pos(), sig, targs, xlist)
		assert(rsig.TypeParams().Len() == 0) // 签名不再通用
		check.recordInstance(call.Fun, targs, rsig)

		// 优化：只有调整参数列表，我们
		// 才需要从调整后的列表中计算；否则我们可以使用结果签名的参数列表。
		if adjusted {
			sigParams = check.subst(call.Pos(), sigParams, makeSubstMap(sig.TypeParams().list(), targs), nil).(*Tuple)
		} else {
			sigParams = rsig.params
		}
	}

	// 检查参数
	if len(args) > 0 {
		context := check.sprintf("argument to %s", call.Fun)
		for i, a := range args {
			check.assignment(a, sigParams.vars[i].typ, context)
		}
	}

	return
}

var cgoPrefixes = [...]string{
	"_Ciconst_",
	"_Cfconst_",
	"_Csconst_",
	"_Ctype_",
	"_Cvar_", // 实际上是一个指向var 
	"_Cfpvar_fp_",
	"_Cfunc_",
	"_Cmacro_", // 函数的指针，用于计算扩展表达式
}

func (check *Checker) selector(x *operand, e *syntax.SelectorExpr, def *Named) {
	// 必须在“goto Error”语句
	var (
		obj      Object
		index    []int
		indirect bool
	)

	sel := e.Sel.Value
	// 如果标识符引用包，请在这里处理所有
	// 所以我们不需要操作数的“包”模式：包名
	// 只能出现在映射到
	// 选择器表达式的限定标识符中。
	if ident, ok := e.X.(*syntax.Name); ok {
		obj := check.lookup(ident.Value)
		if pname, _ := obj.(*PkgName); pname != nil {
			assert(pname.pkg == check.pkg)
			check.recordUse(ident, pname)
			pname.used = true
			pkg := pname.imported

			var exp Object
			funcMode := value
			if pkg.cgo {
				// cgo特殊情况C.malloc:它是
				// 重写为_CMalloc，不支持两个结果调用。
				if sel == "malloc" {
					sel = "_CMalloc"
				} else {
					funcMode = cgofunc
				}
				for _, prefix := range cgoPrefixes {
					// cgo对象是当前包的一部分（在文件
					// _cgo_gotypes.go中）。使用常规查找。
					_, exp = check.scope.LookupParent(prefix+sel, check.pos)
					if exp != nil {
						break
					}
				}
				if exp == nil {
					check.errorf(e.Sel, "%s not declared by package C", sel)
					goto Error
				}
				check.objDecl(exp, nil)
			} else {
				exp = pkg.scope.Lookup(sel)
				if exp == nil {
					if !pkg.fake {
						if check.conf.CompilerErrorMessages {
							check.errorf(e.Sel, "undefined: %s.%s", pkg.name, sel)
						} else {
							check.errorf(e.Sel, "%s not declared by package %s", sel, pkg.name)
						}
					}
					goto Error
				}
				if !exp.Exported() {
					check.errorf(e.Sel, "%s not exported by package %s", sel, pkg.name)
					// 确定继续
				}
			}
			check.recordUse(e.Sel, exp)

			// 简化版的*语法代码。名称：
			// -导入的对象始终是完全初始化的
			switch exp := exp.(type) {
			case *Const:
				assert(exp.Val() != nil)
				x.mode = constant_
				x.typ = exp.typ
				x.val = exp.val
			case *TypeName:
				x.mode = typexpr
				x.typ = exp.typ
			case *Var:
				x.mode = variable
				x.typ = exp.typ
				if pkg.cgo && strings.HasPrefix(exp.name, "_Cvar_") {
					x.typ = x.typ.(*Pointer).base
				}
			case *Func:
				x.mode = funcMode
				x.typ = exp.typ
				if pkg.cgo && strings.HasPrefix(exp.name, "_Cmacro_") {
					x.mode = value
					x.typ = x.typ.(*Signature).results.vars[0].typ
				}
			case *Builtin:
				x.mode = builtin
				x.typ = exp.typ
				x.id = exp.id
			default:
				check.dump("%v: unexpected object %v", posFor(e.Sel), exp)
				unreachable()
			}
			x.expr = e
			return
		}
	}

	check.exprOrType(x, e.X, false)
	switch x.mode {
	case typexpr:
		// 不要为“类型t.x”崩溃（was问题#51509）
		if def != nil && x.typ == def {
			check.cycleError([]Object{def.obj})
			goto Error
		}
	case builtin:
		check.errorf(e.Pos(), "cannot select on %s", x)
		goto Error
	case invalid:
		goto Error
	}

	obj, index, indirect = LookupFieldOrMethod(x.typ, x.mode == variable, check.pkg, sel)
	if obj == nil {
		// 如果基础类型无效，不要报告另一个错误（问题#49541）。
		if under(x.typ) == Typ[Invalid] {
			goto Error
		}

		if index != nil {
			// TODO（gri）应提供发生冲突的实际类型
			check.errorf(e.Sel, "ambiguous selector %s.%s", x.expr, sel)
			goto Error
		}

		if indirect {
			check.errorf(e.Sel, "cannot call pointer method %s on %s", sel, x.typ)
			goto Error
		}

		var why string
		if isInterfacePtr(x.typ) {
			why = check.interfacePtrError(x.typ)
		} else {
			why = check.sprintf("type %s has no field or method %s", x.typ, sel)
			// 检查sel的大小写是否重要，并在这种情况下提供更好的错误消息。
			// TODO（gri）此代码只查看第一个字符，但LookupFieldOrMethod具有用于不区分大小写查找的
			// （内部）机制。我们应该用它来代替。
			if len(sel) > 0 {
				var changeCase string
				if r := rune(sel[0]); unicode.IsUpper(r) {
					changeCase = string(unicode.ToLower(r)) + sel[1:]
				} else {
					changeCase = string(unicode.ToUpper(r)) + sel[1:]
				}
				if obj, _, _ = LookupFieldOrMethod(x.typ, x.mode == variable, check.pkg, changeCase); obj != nil {
					why += ", but does have " + changeCase
				}
			}
		}
		check.errorf(e.Sel, "%s.%s undefined (%s)", x.expr, sel, why)
		goto Error
	}

	// 方法可能尚未完全设置签名
	if m, _ := obj.(*Func); m != nil {
		check.objDecl(m, nil)
	}

	if x.mode == typexpr {
		// 方法表达式
		m, _ := obj.(*Func)
		if m == nil {
			// TODO（gri）应检查sel的大小写是否重要，并提供更好的错误消息，在这种情况下
			check.errorf(e.Sel, "%s.%s undefined (type %s has no method %s)", x.expr, sel, x.typ, sel)
			goto Error
		}

		check.recordSelection(e, MethodExpr, x.typ, m, index, indirect)

		sig := m.typ.(*Signature)
		if sig.recv == nil {
			check.error(e, "illegal cycle in method declaration")
			goto Error
		}

		// 接收方类型成为方法表达式函数类型的第一个函数
		// 参数的类型。
		var params []*Var
		if sig.params != nil {
			params = sig.params.vars
		}
		// 在命名/未命名参数方面保持一致。类型检查不需要使用
		// ，但新构造的签名可能会在错误消息中出现
		// ，然后具有混合的命名/未命名参数。
		// （另一种选择是不打印错误的参数名，
		// ，但查看它们很有用；这很便宜，方法表达式
		// 很少。）
		name := ""
		if len(params) > 0 && params[0].name != "" {
			// 需要名称
			name = sig.recv.name
			if name == "" {
				name = "_"
			}
		}
		params = append([]*Var{NewVar(sig.recv.pos, sig.recv.pkg, name, x.typ)}, params...)
		x.mode = value
		x.typ = &Signature{
			tparams:  sig.tparams,
			params:   NewTuple(params...),
			results:  sig.results,
			variadic: sig.variadic,
		}

		check.addDeclDep(m)

	} else {
		// 常规选择器
		switch obj := obj.(type) {
		case *Var:
			check.recordSelection(e, FieldVal, x.typ, obj, index, indirect)
			if x.mode == variable || indirect {
				x.mode = variable
			} else {
				x.mode = value
			}
			x.typ = obj.typ

		case *Func:
			// TODO（gri）如果我们需要考虑接收方的
			// 可寻址性，我们应该报告类型&（x.typ）吗？
			check.recordSelection(e, MethodVal, x.typ, obj, index, indirect)

			x.mode = value

			// 删除接收器
			sig := *obj.typ.(*Signature)
			sig.recv = nil
			x.typ = &sig

			check.addDeclDep(obj)

		default:
			unreachable()
		}
	}

	// 一切顺利
	x.expr = e
	return

Error:
	x.mode = invalid
	x.expr = e
}

// 使用类型检查每个参数。
// 用于确保在存在其他错误的情况下计算表达式
// （并且“使用”了变量）。
// 参数可能为零。
// TODO（gri）使其接受[]语法。当我们有一个ListXPR时，是否使用解包函数？
func (check *Checker) use(arg ...syntax.Expr) {
	var x operand
	for _, e := range arg {
		switch n := e.(type) {
		case nil:
			// 一些AST字段可能为零（例如syntax.SliceExpr.Index的元素）
			// TODO（gri）这些字段真的可以在这里使用吗？
			continue
		case *syntax.Name:
			// 评估空白
			if n.Value == "_" {
				continue
			}
		case *syntax.ListExpr:
			check.use(n.ElemList...)
			continue
		}
		check.rawExpr(&x, e, nil, false)
	}
}
